e.Toscana Compiance 
Request for Comments: 1 
Del: 15/7/2006 
Categoria: Infrastrutturale

	Accordo di Servizio Parte Comune (ASPC) e.Toscana

Abstract 
======== 
Per instaurare una relazione di servizio tra sistemi  obbligatorio definire in documento un
accordo esplicito sulla erogazione / fruizione delle prestazioni di servizio.
Tale documento  detto Accordo di Servizio (AS). 
Le informazioni contenute nell' AS sono di natura: 
- non formale (quindi rivolte alle persone) 
- formali (quindi rivolte alle applicazioni) 

Laccordo di servizio  composto da una parte comune (ASPC), che formalizza gli
aspetti riusabili in differenti contesti, e da una parte specifica (ASPS), che
precisa e dettaglia la parte comune definendola per una particolare coppia
(erogatore, fruitore). Questa RFC intende definire quali documenti compongono
l'ASPC.

Indice 
====== 
1. Introduzione 
2. Convenzioni 
3. Definizioni 
4. Accordo di Servizio Parte Comune 
4.1 Specifica Formale 
4.1.1 Specifica dellinterfaccia 
4.1.1.1 Types.xsd 
4.1.1.2 WSDL del servizio a livello di scenario di coordinamento (concettuale) 
4.1.1.3 WSDL della parte di competenza del fruitore a livello di scambio elementare di messaggi (logico) 
4.1.1.4 WSDL della parte di competenza dellerogatore a livello di scambio elementare dei messaggi (logico)
4.1.2 Specifica della semantica dellinformazione veicolata 
5. Riferimenti 
6. Note 
7. Autori

1. Introduzione 
=============== 
Una applicazione eroga / fruisce dei servizi utilizzando le intefacce messe a
disposizione dalle Porte di Dominio collacate sui NAL messi a disposizione da
Regione Toscana agli Enti.Sfruttando tale interfacce potr:
- fruire delle prestazioni di servizio erogate da altri soggetti della comunit SPCoop e.Toscana 
- erogare delle prestazioni di servizio agli altri Soggetti della comunit SPCoop e.Toscana 

I Soggetti della comunit SPCoop e.Toscana avranno la possibilit di: 
* reperire informazioni messe a disposizione dalla comunit con estrema naturalezza e con costi minimi 
* arricchire le proprie informazioni con altre reperite dalla comunit con estrema naturalezza e con costi minimi 
* distribuire applicazioni che condividono informazioni 
* minimizzare i costi necessari per adempiere ad un debito informativo verso altri Soggetti 

Prerequisito alla nascita di una comunit di soggetti  la stipula di
accordi chiari tra i partecipanti. L'AS  il contratto che lega il fornitore di
servizio all'erogatore in termini di: 
- specifiche per limplementazione dei sistemi erogatore/fruitore 
- riferimenti per lesecuzione e la gestione dei sistemi erogatore/fruitore 

Una parte di questo contratto  riusabile nell'ambito di pi contraenti. 
Tale parte di accordo di servizio si chiama Parte Comune. 

La parte comune di un accordo di servizio (ASPC) formalizza gli aspetti riusabili
in differenti contesti dell'AS. L'obiettivo di questa RFC  chiarire quali
documenti compongono l'accordo di servizio parte comune (ASPC).

2. Convenzioni 
============== 
* AS: Accordo di Servizio 
* ASPC: Accordo di Servizio Parte Comune 
* ASPS: Accordo di Servizio Parte Specifica 
* CART: Cooperazione Applicativa Regionale Toscana 

3. Definizioni 
============== 
* Servizio: 
insieme dei risultati prodotti dai trattamenti effettuati dal sistema Erogatore
e utilizzati dal sistema Fruitore

* comunit SPCoop e.Toscana: 
comunit di Soggetti che espongono e integrano le loro applicazioni per mezzo di
servizi con la finalit di creare uno spazio comune di informazioni alimentato e
fruito dai sistemi informativi dei Soggetti partecipanti 

* Applicazione e.Toscana Compliant: 
applicazione conforme alle specifiche infrastrutturali emanate dal Comitato per
l'e.Toscana Compliant. Il certificato di conformit e.Toscana Compliance 
rilasciato dal Centro Tecnico per l'e.Toscana Compliance.

* Erogatore di un servizio:
Soggetto che a riceve delle informazioni da trattare

* Fruitore di un servizio:
Soggetto che invia della informazioni che l'erogatore dovr trattare

4. Accordo di Servizio Parte Comune 
===================================
Il formato di un accordo di servizio consiste in un insieme di file raccolti in
un archivio compresso secondo la codifica zip, aderenti a vari formati standard
di definizione di specifiche caratteristiche dellaccordo, come XML-SChema o
WSDL ed altri formalismi realizzati ad-hoc.

La cartella che raccoglier i documenti deve avere il seguente nome:
RFC_NUM_<numero rfc cui l'accordo di servizio si riferisce> Ad esempio nel caso
l'accordo di servizio si riferisca all'RFC numero 3 il nome della cartella dovr
essere RFC_NUM_3.

Nella cartella dovr essere presente un documento che riporta le seguenti
informazioni:
- Numero RFC cui l'accordo di servizio si riferisce
- Versione dell'RFC cui l'accordo di servizio si riferisce
- URL all'RFC cui l'AS si riferisce
- Nome, Cognome, mail e telefono di colui che ha redatto l'accordo di servizio
- Versione dell'accordo di servzio
Dovr essere presente una sottocartella chiamata WSDL contenente i documenti
indicati ai punti:
- 4.2.1.1
- 4.2.1.2
- 4.2.1.3
- 4.2.1.4

4.1 Specifica Formale 
=====================

4.1.1 Specifica dellinterfaccia 
================================ 
La specifica dell'interfaccia si compone di quattro documenti :
1) Types.xsd
2) WSDL "concettuale" 
3) WSDL "logico" dell'erogatore 
4) WSDL "logico" del fruitore 

Le dizioni "concettuale" e "logico" con cui vengono etichettati i file WSDL sono utilizzati
in analogia a quanto viene proposto nelle comuni metodologie per il progetto
delle basi di dati. 
A livello concettuale viene descritta l'interfaccia del servizio
indipendentemente dallo scambio elementare dei messaggi su cui poi
effettivamente il servizio viene realizzato.
Il livello logico descrive come l'interfaccia del servizio viene effettivamente
realizzata usando particolari scambi elementari di messaggi.
Infine ci sar un livello fisico in cui verranno dettagliati i binding e le URI
di accesso da parte di questi due web service. 
Questo per non  incluso nella parte comune ma bens nella parte specifica.

4.1.1.1 Types.xsd
=================
Il file Types.xsd  estraibile dall'RFC Applicativo e.Toscana.

4.1.1.2 WSDL del servizio a livello di scenario di coordinamento (concettuale)
============================================================================
In questo WSDL si:
	- include il documento Types.xsd
	- definiscono i messaggi in termini dei tipi definiti in Types.xsd
	- definiscono i portType e le relative operazioni in termini di messaggi di ingresso e uscita
	- ulteriori parametri di specializzazione delle operazioni
	
4.1.1.2.1 Specifiche nella definizione dei messaggi
===================================================
La definizione dei messaggi deve essere conforme alla seguente sintassi:
	<Direzione>_<TipologiaScenario>_<NomeOperazione>_Msg		
dove:
	<Direzione>         := 
		richiesta | 
		risposta | 
		segnalazione
	<TipologiaScenario> := 
		RichiestaSenzaRisposta | 
		RichiestaRispostaSincrona |
		RichiestaRispostaAsincrona | 
		NotificazioneRisposta |
		NotificazioneSenzaRisposta

4.1.1.2.2 Ulteriori paramterizzazioni delle operazioni
======================================================
Per ogni operazione indicato nel WSDL concettuale  possibile indicare ulteriori
parametri di configurazione. I possibili parametri di configurazione devono
essere messi come annotazioni nel WSDL nella zona in cui si definisce la singola
azione. I possibili parametri di configurazione sono:

- Trasmissione inoltro:
Indica il valore dell'eventuale attributo inoltro del Profilo Trasmissione del
protocollo SPCoop.

- Profilo Trasmissione:
Indica l'eventuale abilitazione della conferma ricezione del protocollo SPCoop.

- Consegna in Ordine:	
Indica l'eventuale abilitazione della consegna in ordine del protocollo SPCoop.

- Scadenza:			
Indica l'eventuale scadenza dei messaggi SPCoop. Il CART impone comunque una
scadenza massima di 10 giorni.

4.1.1.2.3 Esempio di WSDL concettuale
======================================
Quello che segue  un esempio di WSDL concettuale:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:tns="http://www.regione.toscana.it/movimentazione_turistica/concettuale"
	xmlns:types="http://www.regione.toscana.it/movimentazione_turistica/types"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	name="MovimentazioneTuristica"
	targetNamespace="http://www.regione.toscana.it/movimentazione_turistica/concettuale">


	<!-- Importiamo i types definiti nel documento di definizione dei tipi -->
	<wsdl:types>
	  <xsd:schema>
		<xsd:import
			namespace="http://www.regione.toscana.it/movimentazione_turistica/types"
			schemaLocation="movimentazione_turistica_types.xsd" />
	  </xsd:schema>
	</wsdl:types>

	<!-- 
		Dichiarazione dei messaggi con sintassi conforme 
		a SPCoop - Accordo di servizio v1.0_20051014:
		
		<Direzione>_<TipologiaScenario>_<NomeOperazione>_Msg
		
		dove:
		<Direzione>         := richiesta | risposta | segnalazione
		<TipologiaScenario> := RichiestaSenzaRisposta | RichiestaRispostaSincrona |
		RichiestaRispostaAsincrona | NotificazioneRisposta |
		NotificazioneSenzaRisposta
	-->

	<wsdl:message
		name="richiesta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg">
		<wsdl:part name="parameters"
			element="types:richiesta_RichiestaRispostaSincrona_InvioDatiStruttura" />
	</wsdl:message>

	<wsdl:message
		name="risposta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg">
		<wsdl:part name="parameters"
			element="types:risposta_RichiestaRispostaSincrona_InvioDatiStruttura" />
	</wsdl:message>

	<wsdl:portType name="MovimentazioneTuristicaPortType">
		<wsdl:operation
			name="InvioDatiStruttura">
			<wsdl:input
				message="tns:richiesta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg" />
			<wsdl:output
				message="tns:risposta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg" />
		</wsdl:operation>
	</wsdl:portType>
</wsdl:definitions>

Per una descrizione degli scenari do coordinamento si veda il paragrafo 3.1.1
dell'RFC "RFC Applicativo e.Toscana".

4.1.1.2 WSDL della parte di competenza del fruitore a livello di scambio elementare di messaggi (logico)
======================================================================================================
Documento WSDL a "livello logico" del fruitore che descrive le operazioni
offerte dai Web Service da dispiegare concretamente sul lato fruitore affinch
il servizio sia effettivamente realizzato. Questo WSDL  necessario per le
risposte asincrone e le notificazioni. Il documento WSDL contiene solo i
costrutti TYPES, MESSAGE, PORT TYPE, e le OPERATION possono essere solamente 2
dei 4 tipi previsti dal linguaggio: one-way e request/reply.

4.1.1.2.1 Esempio di WSDL logico fruitore
=========================================
Un esempio di WSDL logico fruitore  il seguente:
<!--
 Il documento e' vuoto in quanto il fruitore non deve realizzare 
 alcun servizio in questo caso.
 
 Da SPCoop - Accordo di Servizio_v1_0_20051014 sez. 6.3.1:
 
  "Anche nel caso di servizi che non richiedono Web Service 
   sul lato fruitore (servizi sincroni ovvero senza operazioni di notificazione), 
   quest'ultimo WSDL deve essere presente come
   documento vuoto, ad indicare appunto che sul lato fruitore concretamente 
   non  necessario realizzare nulla di complesso per usufruire del servizio. 
   
   (L'affermazione ''non deve realizzare nulla di complesso'' va intesa 
   nel senso che niente di complesso (''logica servente'') deve essere 
   realizzato sul lato fruitore). "
 -->

4.1.1.3 WSDL della parte di competenza dellerogatore a livello di scambio elementare dei messaggi (logico)
=========================================================================================================
Documento WSDL a "livello logico" dell' erogatore che descrive le operazioni
offerte dai Web Service da dispiegare concretamente sul lato erogatore affinch
il servizio sia effettivamente realizzato. Il documento WSDL contiene solo i
costrutti TYPES, MESSAGE, PORT TYPE, e le OPERATION possono essere solamente 2
dei 4 tipi previsti dal linguaggio: one-way e request/reply.

4.1.1.3.1 Esempio di WSDL logico erogatore
==========================================
Quello che segue  un esempio di WSDL logico lato erogatore di un servizio

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:tns="http://www.regione.toscana.it/movimentazione_turistica/erogatore"
	xmlns:types="http://www.regione.toscana.it/movimentazione_turistica/types"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	name="MovimentazioneTuristica"
	targetNamespace="http://www.regione.toscana.it/movimentazione_turistica/erogatore">

    <!-- 
     Visto che il fruitore non espone servizi, il WSDL logico dell'erogatore 
     e' praticamente identico al WSDL concettuale 
     (fatta eccezione per il targetNamespace).
     http://www.regione.toscana.it/movimentazione_turistica/erogatore
     -->

	<!-- Importiamo i types definiti nel documento di definizione dei tipi -->
	<wsdl:types>
	  <xsd:schema>
		<xsd:import
			namespace="http://www.regione.toscana.it/movimentazione_turistica/types"
			schemaLocation="movimentazione_turistica_types.xsd" />
	  </xsd:schema>
	</wsdl:types>

	<wsdl:message
		name="richiesta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg">
		<wsdl:part name="parameters"
			element="types:richiesta_RichiestaRispostaSincrona_InvioDatiStruttura" />
	</wsdl:message>

	<wsdl:message
		name="risposta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg">
		<wsdl:part name="parameters"
			element="types:risposta_RichiestaRispostaSincrona_InvioDatiStruttura" />
	</wsdl:message>

	<wsdl:portType name="MovimentazioneTuristicaPortType">
		<wsdl:operation
			name="InvioDatiStruttura">
			<wsdl:input
				message="tns:richiesta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg" />
			<wsdl:output
				message="tns:risposta_RichiestaRispostaSincrona_InvioDatiStruttura_Msg" />
		</wsdl:operation>
	</wsdl:portType>
</wsdl:definitions>

5. Riferimenti 
============== 
Documenti rilasciati dal Centro Nazionale per
lInformatica nella Pubblica Amministrazione (CNIPA): SPC, Sistema pubblico di
cooperazione: Accordo di Servizio, Versione 1.0, CNIPA, 14 Ottobre 2005

6. Note 
=======

7. Autori 
=========
Walter Volpi - walter.volpi@regione.toscana.it
